feat(plugin-auth): the SSO Providers form sets, shows and clears the groups claim - #31755

Requested by Steve · project thread

Fixes #31666

Clause-②: yes (widening)
Metadata-protocol: none

维护者速读

• 改了什么：Setup → SSO Providers 表单现在能设置、查看和清除 SSO 组声明（groups claim），写入的位置与 /sso/register 完全相同：mapping.extraFields.groups。
• 为什么改：feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 之后登录会按 IdP 组授予权限集，但组声明只能经 API 配置，管理员在界面上无法完成这一步。
• 风险与回滚：只新增两个仅限平台管理员的动作和两个注册参数；另修了一个现存缺陷（带 oidcConfig 的 update-provider 对密钥存于 sys_secret 的 OIDC 提供方一律返回 400）。回滚即 revert 本 PR。
• 先看：packages/plugins/plugin-auth/src/register-sso-provider.ts 末尾的两个桥，以及 objectql-adapter.ts 里 update 回显的密钥注入。
• 两分钟验证：pnpm --filter @objectstack/plugin-auth exec vitest run src/sso-oidc-refusal-cause.test.ts src/register-sso-provider.test.ts src/admin-sso-bridge-gate.test.ts。
• 需要你做的：无；两个新路由名由席位裁定（见下）。

What changes

The Setup → SSO Providers form is metadata (sys_sso_provider actions with flat params that post to plugin-auth /admin/sso/* bridges), not console code, so the whole change sits in plugin-auth and platform-objects. Nothing under ui/ or packages/spec/** changes.

• Register SSO Provider gains Map: Groups claim and Register SAML Provider gains Map: Groups attribute. A non-blank value lands on mapping.extraFields.groups, exactly where POST /api/v1/auth/sso/register stores it. Blank stores no extraFields, as today.
• Show Groups Claim posts to the new POST /api/v1/auth/admin/sso/get-groups-claim, which reads the stored row (system read, oidc_config / saml_config recovered) and answers only { providerId, groupsClaim }.
• Edit Groups Claim posts to the new POST /api/v1/auth/admin/sso/set-groups-claim. It merges the claim into the stored mapping (every other member kept verbatim), writes through the vendor's own /sso/update-provider, and reads the claim back. A blank claim deletes extraFields.groups (and an emptied extraFields), so the provider signs users in exactly like one saved without it.
• Both routes run gateAdmin first, the platform-admin gate of the other /admin/sso bridges. A refused vendor update answers its status with the standard code for it and a fixed sentence; the vendor's body is never relayed, so no other config member (client secret, certificate, endpoints, other mapping members) can reach an answer.
• Fix: @better-auth/sso reads the provider for /sso/update-provider through lockSSOProviderRow, which is an adapter update. That echo did not run the read half (injectClientSecretOnRead), so any update-provider carrying an oidcConfig for a provider whose secret is held in sys_secret was refused 400 "clientSecret is required". The adapter's update now carries the secret and the IdP-initiated column into its echo like every other provider read.
• Two route-ledger rows, two platform-objects affordance rows, docs page content/docs/permissions/sso.mdx updated, translations for ten locales.
• The feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 grant logic (sso-group-projection.ts) is untouched.

New public route names (/admin/sso/get-groups-claim, /admin/sso/set-groups-claim) and action names (show_sso_groups_claim, edit_sso_groups_claim) follow the /admin/sso/* and *_sso_* house spelling; they are the seat's call. No new error code: 400 VALIDATION_ERROR / INVALID_REQUEST, 404 RESOURCE_NOT_FOUND, 401/403 from the existing gate.

Why

Since #31657 an SSO sign-in grants the permission sets mapped to the provider's IdP groups, read from mapping.extraFields.groups. Only the vendor register API could set that member (documented by #31664); an administrator working in Setup had no way to configure it.

Verification

Clause-② measured: on base POST /api/v1/auth/admin/sso/set-groups-claim and get-groups-claim are not mounted and the register forms carry no groups param; on head both routes answer a platform admin 200 and the register forms accept the new param. A widening only: no request accepted on main is now refused.

Tests (all import src):

• sso-oidc-refusal-cause.test.ts, new describe: a form save with a claim stores the register door's mapping and the next sign-in grants the mapped set (the feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 pin shape). CONTROL: a blank claim writes nothing and grants nothing. CONTROL: Show on a register-door row answers groups, then a clear removes it. Round trip on a rich mapping (register-door row and a row this action changed): every other member kept verbatim.
• register-sso-provider.test.ts: both register forms store the claim where the register door does (compared to a direct /sso/register row), CONTROL without it; the bridges' merge, clear, 404 and 400; a no-leak pin (client secret, certificate, client id, IdP URL, other mapping members never appear in any answer, including a vendor refusal carrying them; data keys are exactly providerId and groupsClaim).
• admin-sso-bridge-gate.test.ts: for both routes, anonymous 401 and member / org-admin / position-named-admin 403 with neither the store read nor the vendor called; platform admin 200.
• sso-client-secret-at-rest.test.ts ③b: an update-provider carrying only oidcConfig.mapping is accepted and the secret still reads back.

Ablations (each restored, git diff HEAD empty afterwards):

• Gate removed from set-groups-claim → 4 gate tests red (expected 200 to be 401 / 403).
• Vendor refusal body relayed → the no-leak test red.
• Mapping added to the show answer → 2 tests red (data had 3 keys, expected 2).
• Echo injection removed from the adapter update → ③b and the round trip red (clientSecret is required …, 400).

Runs: plugin-auth full suite 4431 passed, 10 skipped, 1 red (the route-ledger pin, which hand-lists the mounts); that file re-run green (10/10) after the pin named the two routes; platform-objects 120 files / 1933 tests green; typecheck green for both packages; lint (eslint --no-inline-config) clean on both packages; check:i18n, check:i18n-coverage and check:auth-mount-ledger OK; every dispatch-gates --commands command run and reconciled with --ran. Dogfood, run locally under the verify lock after the sweep fix: the whole @objectstack/dogfood package 440 files passed, 3 skipped; 3653 tests passed, 41 skipped; 0 failed. The five admin suites together 5/5 files, 34/34 tests. Control: without the new entries the non-admin sweep is red at :618 with the queue's signature.

Forced test edits (existing tests changed because the surface grew):

• sso-oidc-refusal-cause.test.ts: bootGroupEngine now registers the auth object extensions and sys_secret and sets a fake crypto provider, so the harness holds a client secret the way production does.
• platform-objects.test.ts: two rows in the action table (show_sso_groups_claim, edit_sso_groups_claim).
• platform-admin-affordance-standing.test.ts: the same two actions on the floor list.
• auth-route-ledger.conformance.test.ts: the hand-written objectstack-mount pin names the two new routes.
• packages/qa/dogfood/test/admin-platform-admin-standing.dogfood.test.ts: the two routes join ADMITTED (ADR-0068 gate first) with probe bodies; the admin reaches the handler and gets 404 for the unknown probe provider, nothing moves.
• packages/qa/dogfood/test/admin-route-nonadmin-refusal.dogfood.test.ts: the two routes join the objectstack-gate bucket with the same probe bodies (anonymous 401, member 403; admin measured 404 RESOURCE_NOT_FOUND).

Both dogfood sweeps derive the served /admin/ route set and refuse an unclassified mount; PR CI does not run the dogfood shards, so the merge queue caught them (run 42562448270, Dogfood 3/3; then Dogfood 1/3). Census of packages/qa/dogfood/test: only these two files derive the /admin/ set. admin-credential-lifecycle, admin-identity-audit-trail and admin-ledger-decision-metadata name fixed routes and need no registration.

Out of scope, noted: ADR-0011's "Not assessed" list could name the two new actions (governed surface, left alone); the cloud auth proxy must mount the two new routes to serve them there.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (Not touched.)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English. (The ## 维护者速读 section is Chinese by the dispatch order.)
• The Before Submitting list in CONTRIBUTING.md is done.

Generated by Claude Code